package net.oxygen.upload.service;

import net.oxygen.upload.dto.FileChunkDTO;
import net.oxygen.upload.request.FileChunkInitTaskReq;
import net.oxygen.upload.request.FileChunkMergeReq;

/**
 * 文件分片服务接口
 * <p>
 * 提供大文件分片上传的核心功能，支持：
 * - 分片上传任务的创建和管理
 * - 分片上传URL的生成
 * - 分片合并
 * - 上传进度查询
 * - 断点续传等功能
 * </p>
 *
 * @author chenweiwei
 * @version 1.0
 * @since 2023-03-24
 */
public interface IFileChunkService {

    /**
     * 初始化文件分片上传任务
     * <p>
     * 创建一个新的分片上传任务，生成唯一的uploadId，
     * 并在数据库中记录分片信息，为后续分片上传做准备
     * </p>
     *
     * @param req 分片上传任务初始化请求，包含文件信息、分片大小等
     * @return 分片任务信息，包含uploadId和分片数量等
     */
    FileChunkDTO initFileChunkTask(FileChunkInitTaskReq req);

    /**
     * 生成预签名的分片上传URL
     * <p>
     * 为指定的分片生成一个带有临时授权的URL，
     * 客户端可直接通过该URL将分片上传到存储服务，无需经过应用服务器
     * </p>
     *
     * @param identifier 文件唯一标识（MD5值）
     * @param partNumber 分片序号，从1开始
     * @return 预签名的上传URL，有效期通常为1小时
     */
    String genPreSignUploadUrl(String identifier, int partNumber);

    /**
     * 合并文件分片
     * <p>
     * 当所有分片上传完成后，将分片合并成完整的文件
     * 合并过程包括：
     * 1. 调用存储服务的分片合并API
     * 2. 更新数据库中的文件记录
     * 3. 清理分片上传任务相关数据
     * </p>
     *
     * @param req 分片合并请求，包含文件唯一标识等信息
     */
    void mergeFileChunk(FileChunkMergeReq req);

    /**
     * 查询文件分片上传进度
     * <p>
     * 获取特定文件的已上传分片信息，用于：
     * 1. 断点续传场景，确定哪些分片已上传成功
     * 2. 显示上传进度
     * 3. 上传任务恢复
     * </p>
     *
     * @param identifier 文件唯一标识（MD5值）
     * @return 分片信息，包含已上传分片列表和上传任务基本信息
     */
    FileChunkDTO listFileChunk(String identifier);

    /**
     * 直接上传分片到存储服务
     * <p>
     * 通过应用服务器代理，将分片数据上传到存储服务
     * 相比预签名URL方式，此方法适用于：
     * 1. 需要更严格的访问控制
     * 2. 客户端无法直接访问存储服务的场景
     * 3. 需要在上传过程中进行额外处理的情况
     * </p>
     * 
     * @param identifier 文件唯一标识（MD5值）
     * @param partNumber 分片序号，从1开始
     * @param file       分片文件数据的字节数组
     * @return 是否上传成功
     */
    boolean uploadPart(String identifier, int partNumber, byte[] file);
}
